


RCSINTRO(1)              USER COMMANDS                RCSINTRO(1)



NAME
     rcsintro - introduction to RCS commands

DESCRIPTION
     The Revision Control System (RCS) manages multiple revisions
     of  files.   RCS  automates the storing, retrieval, logging,
     identification, and merging of revisions.  RCS is useful for
     text that is revised frequently, for example programs, docu-
     mentation, graphics, papers, and form letters.

     The basic user interface is extremely  simple.   The  novice
     only  needs  to  learn  two  commands: ci(1) and co(1).  ci,
     short for "check in", deposits the contents of a  file  into
     an  archival  file called an RCS file.  An RCS file contains
     all revisions of a particular file.  co,  short  for  "check
     out", retrieves revisions from an RCS file.

  Functions of RCS
     o+    Store and retrieve multiple  revisions  of  text.   RCS
          saves  all  old  revisions  in  a  space efficient way.
          Changes no longer destroy  the  original,  because  the
          previous revisions remain accessible.  Revisions can be
          retrieved according to ranges of revision numbers, sym-
          bolic names, dates, authors, and states.

     o+    Maintain a complete history of changes.  RCS  logs  all
          changes  automatically.  Besides the text of each revi-
          sion, RCS stores the  author,  the  date  and  time  of
          check-in,  and  a  log  message summarizing the change.
          The logging makes it easy to find out what happened  to
          a  module, without having to compare source listings or
          having to track down colleagues.

     o+    Resolve access conflicts.  When two or more programmers
          wish  to  modify the same revision, RCS alerts the pro-
          grammers and prevents one modification from  corrupting
          the other.

     o+    Maintain  a  tree  of  revisions.   RCS  can   maintain
          separate  lines  of  development  for  each module.  It
          stores a tree structure that represents  the  ancestral
          relationships among revisions.

     o+    Merge revisions and resolve  conflicts.   Two  separate
          lines  of  development  of a module can be coalesced by
          merging.  If the revisions to be merged affect the same
          sections  of  code, RCS alerts the user about the over-
          lapping changes.

     o+    Control releases and configurations.  Revisions can  be
          assigned symbolic names and marked as released, stable,
          experimental,    etc.     With    these     facilities,



GNU                  Last change: 1991/04/21                    1






RCSINTRO(1)              USER COMMANDS                RCSINTRO(1)



          configurations  of  modules can be described simply and
          directly.

     o+    Automatically identify each revision with  name,  revi-
          sion number, creation time, author, etc.  The identifi-
          cation is like a stamp  that  can  be  embedded  at  an
          appropriate place in the text of a revision.  The iden-
          tification makes it simple to determine which revisions
          of which modules make up a given configuration.

     o+    Minimize secondary storage.   RCS  needs  little  extra
          space  for  the  revisions  (only the differences).  If
          intermediate revisions are deleted,  the  corresponding
          deltas are compressed accordingly.

  Getting Started with RCS
     Suppose you have a file f.c that you wish to put under  con-
     trol  of  RCS.  If you have not already done so, make an RCS
     directory with the command

          mkdir  RCS

     Then invoke the check-in command

          ci  f.c

     This command creates an  RCS  file  in  the  RCS  directory,
     stores  f.c  into  it  as revision 1.1, and deletes f.c.  It
     also asks you for a description.  The description should  be
     a  synopsis of the contents of the file.  All later check-in
     commands will ask you for a log entry, which should  summar-
     ize the changes that you made.

     Files in the RCS directory are called RCS files; the  others
     are  called working files.  To get back the working file f.c
     in the previous example, use the check-out command

          co  f.c

     This command extracts the latest revision from the RCS  file
     and  writes  it into f.c.  If you want to edit f.c, you must
     lock it as you check it out with the command

          co  -l  f.c

     You can now edit f.c.

     Suppose after some editing you want  to  know  what  changes
     that you have made.  The command

          rcsdiff  f.c




GNU                  Last change: 1991/04/21                    2






RCSINTRO(1)              USER COMMANDS                RCSINTRO(1)



     tells you the difference between the most recently  checked-
     in  version  and  the  working file.  You can check the file
     back in by invoking

          ci  f.c

     This increments the revision number properly.

     If ci complains with the message

          ci error: no lock set by _y_o_u_r _n_a_m_e

     then you have tried to check in a file even though  you  did
     not  lock  it when you checked it out.  Of course, it is too
     late now to do the check-out with locking,  because  another
     check-out  would  overwrite  your  modifications.   Instead,
     invoke

          rcs  -l  f.c

     This command will lock the latest revision for  you,  unless
     somebody  else  got  ahead  of  you  already.  In this case,
     you'll have to negotiate with that person.

     Locking assures that you, and only you,  can  check  in  the
     next  update,  and  avoids  nasty problems if several people
     work on the same file.  Even if a revision is locked, it can
     still  be checked out for reading, compiling, etc.  All that
     locking prevents is a _c_h_e_c_k-_i_n by anybody but the locker.

     If your RCS file is private, i.e., if you are the only  per-
     son  who is going to deposit revisions into it, strict lock-
     ing is not needed and you can turn it off.  If strict  lock-
     ing is turned off, the owner of the RCS file need not have a
     lock for check-in; all  others  still  do.   Turning  strict
     locking off and on is done with the commands

          rcs  -U  f.c     and     rcs  -L  f.c

     If you don't want to clutter your working directory with RCS
     files,  create  a  subdirectory  called  RCS in your working
     directory, and move all your RCS files there.  RCS  commands
     will  look  first  into that directory to find needed files.
     All the commands discussed above will  still  work,  without
     any modification.  (Actually, pairs of RCS and working files
     can be specified in three ways: (a) both are given, (b) only
     the  working  file is given, (c) only the RCS file is given.
     Both RCS and working files may have arbitrary path prefixes;
     RCS commands pair them up intelligently.)

     To avoid the deletion of the working  file  during  check-in
     (in case you want to continue editing or compiling), invoke



GNU                  Last change: 1991/04/21                    3






RCSINTRO(1)              USER COMMANDS                RCSINTRO(1)



          ci  -l  f.c     or     ci  -u  f.c

     These commands check in f.c as usual, but perform an  impli-
     cit  check-out.   The  first  form also locks the checked in
     revision, the second one doesn't.  Thus, these options  save
     you  one  check-out  operation.  The first form is useful if
     you want to continue editing, the second  one  if  you  just
     want to read the file.  Both update the identification mark-
     ers in your working file (see below).

     You can give ci the number you want assigned to a checked in
     revision.  Assume all your revisions were numbered 1.1, 1.2,
     1.3, etc., and you would like to start release 2.  The  com-
     mand

          ci  -r2  f.c     or     ci  -r2.1  f.c

     assigns the number 2.1 to the new revision.  From  then  on,
     ci  will number the subsequent revisions with 2.2, 2.3, etc.
     The corresponding co commands

          co  -r2  f.c     and     co  -r2.1  f.c

     retrieve the latest revision numbered 2._x and  the  revision
     2.1, respectively.  co without a revision number selects the
     latest revision on the _t_r_u_n_k, i.e. the highest revision with
     a  number  consisting of two fields.  Numbers with more than
     two fields are needed for branches.  For example, to start a
     branch at revision 1.3, invoke

          ci  -r1.3.1  f.c

     This command starts a branch numbered 1 at revision 1.3, and
     assigns  the  number  1.3.1.1 to the new revision.  For more
     information about branches, see rcsfile(5).

  Automatic Identification
     RCS can put special strings  for  identification  into  your
     source  and  object  code.   To  obtain such identification,
     place the marker

          $Id$

     into your text, for instance inside  a  comment.   RCS  will
     replace this marker with a string of the form

          $Id:  _f_i_l_e_n_a_m_e  _r_e_v_i_s_i_o_n  _d_a_t_e  _t_i_m_e  _a_u_t_h_o_r  _s_t_a_t_e  $

     With such a marker on the first page of each module, you can
     always  see  with which revision you are working.  RCS keeps
     the markers up to  date  automatically.   To  propagate  the
     markers  into your object code, simply put them into literal



GNU                  Last change: 1991/04/21                    4






RCSINTRO(1)              USER COMMANDS                RCSINTRO(1)



     character strings.  In C, this is done as follows:

          static char rcsid[] = "$Id$";

     The command ident extracts such markers from any file,  even
     object  code and dumps.  Thus, ident lets you find out which
     revisions of which modules were used in a given program.

     You may also find it useful to put  the  marker  $Log$  into
     your  text,  inside  a comment.  This marker accumulates the
     log messages that are requested during check-in.  Thus,  you
     can  maintain  the  complete  history  of your file directly
     inside it.   There  are  several  additional  identification
     markers; see co(1) for details.

IDENTIFICATION
     Author: Walter F. Tichy.
     Revision Number: 5.1; Release Date: 1991/04/21.
     Copyright 8c9 1982, 1988, 1989 by Walter F. Tichy.
     Copyright 8c9 1990, 1991 by Paul Eggert.

SEE ALSO
     ci(1), co(1),  ident(1),  rcs(1),  rcsdiff(1),  rcsintro(1),
     rcsmerge(1), rlog(1)
     Walter  F.  Tichy,  RCS--A  System  for   Version   Control,
     _S_o_f_t_w_a_r_e--_P_r_a_c_t_i_c_e & _E_x_p_e_r_i_e_n_c_e 15, 7 (July 1985), 637-654.





























GNU                  Last change: 1991/04/21                    5



